System Booster

home *** CD-ROM | disk | FTP | other *** search

/ System Booster / System Booster.iso / Archives / GNU / GNU_TILE_FORTH.lha / doc / forth.txt next >

Wrap

Text File | 1992-08-23 | 44.5 KB | 1,058 lines

FORTH(3X) FORTH(3X) NAME forth forth-83 standard word set and tile forth kernel extensions SYNOPSIS forth DESCRIPTION The required word set of Forth-83 Standard excluding the block file word set and the tile forth kernel extensions. Each "word" (function, procedure, variable, etc) is described with its stack action, parameters, and return values and its code type. The format of the glossary list is: <type> <name> ( <stack-effect> ) [ <mode> ] The <stack-effect> describes the parameter and return values for the word in the following format: ( <arguments> -- <returns>) The arguments and return values are given from left to right with the deepest stack value first. Symbolic names are often used for the arguments while the return values are often only described by data type. The optional <mode> may define how the word is interpreted and when it is visible. The mode "immediate" marks the word as always executed. The mode "execution" reduces the words visibility to only execution, i.e., interpretation, mode. The mode "compilation" reduces the words visibility to only compilation mode. Last, the mode "private" marks the words as only visible in the vocabulary where it is defined. Additional modes are added by other tile forth extensions. The list of required words in the Forth-83 Standard are described in the following sub-sections; "Stack Manipulation", "Memory Access", "Logic", "Arithmetic", "Comparison", "Numeric Conversion", "Control Structures", "Terminal Input/Output", "Interpreter", "Vocabulary", and "Defining Words". Each sub-section is sorted in ASCII order. Stack Manipulation The Forth-83 Standard parameter and return stack manipulation functions. The tile forth kernel also supports the double number stack manipulation extension. code -rot ( x y z -- z x y) The top three stack entries are rotated, forcing the top to become the deepest of the three. code 2>r ( x y -- ) compilation Double "to-r". "x" and "y" are transferred to the return stack. September 17, 1990 1 FORTH(3X) FORTH(3X) code 2drop ( x y -- ) Double "drop". "x" and "y" are dropped. code 2dup ( x1 y1 -- x1 y1 x1 y1) Double "dup". The first pair is copied. code 2over (x1 y1 x2 y2 -- x1 y1 x2 y2 x1 y1) Double "over". The second pair is copied. code 2r> ( -- x y) compilation Double "from-r". "x" and "y" are removed from the return stack and transferred to the data stack. code 2rot ( x1 y1 x2 y2 x3 y3 -- x2 y2 x3 y3 x1 y1) Double "rot". The three pairs change places. code 2swap ( x1 y1 x2 y2 -- x2 y2 x1 y1) Double "swap". The two pairs change places. code >r ( x -- ) compilation Transfer "x" to the return stack. code ?dup ( x -- [x x] or [x]) Duplicate "x" if it is non-zero. code depth ( -- +n) "+n" is the number of values contained in the data stack before "+n" was placed on the stack. code drop ( x -- ) "x" is removed from the stack. code dup ( x -- x x) Duplicate "x". code nip ( x y -- y) The second stack element "x" is removed. code over ( x y -- x y x) A copy of "x" is made and moved over "y". code pick ( +n -- x) "x" is a copy of the "+n"-th stack element, not counting "+n" itself. [0..depth-1] "0 pick" is equivalent to "dup" "1 pick" is equivalent to "over" code r> ( -- x) compilation "x" is removed from the return stack and transferred to the data stack. code r@ ( -- x) compilation "x" is a copy of the top of the return stack. September 17, 1990 2 FORTH(3X) FORTH(3X) code roll ( +n -- ) The "+n"-th stack value, not counting "+n" itself is first removed and then transferred to the top of the stack, moving the remaining values into the vacated position. The parameter should be in the interval: [0..depth-1]. "0 roll" is a null operation "1 roll" is equivalent to "swap" "2 roll" is equivalent to "rot" code rot ( x y z -- y z x) The top three stack entries are rotated, bringing the deepest to the top. code swap ( x y -- y x) The top two stack entries are exchanged. code tuck ( x y -- y x y) A copy of "y" is tucked under "x". Memory Access The Forth-83 Standard memory and data access word set. The tile forth kernel extends the Forth-83 Standard with additional access functions for bit testing and bit field access. All access to memory is achieved through this word set. code ! ( 32b addr -- ) The postfix assignment operator. Store "32b" at "addr". code +! ( x1 addr -- ) "x1" is added to the value at "addr" using the convention for "+". The value at "addr" is assumed to be of size "cell". The sum replaces the original value at "addr". code -match ( addr1 addr2 n -- bool) Matches the strings at address "addr1" and "addr2" of length "n" at the parameter addresses. Returns "false" if the strings are equal else "true". If the length "n" is zero the function will return "true". code -trailing ( addr +n1 -- addr +n2) The character counter "+n1" of a text string beginning at "addr" is adjusted to exclude trailing spaces. If "+n1" is zero, then "+n2" is zero. If the entire string consists of spaces, then "+n2" is zero. code <c@ ( addr -- 8b) "8b" is the value at "addr". The value is sign extended to the stack (cell) width. September 17, 1990 3 FORTH(3X) FORTH(3X) code <f@ ( x p w -- y) Field access within a 32-bit quantity. "y" are the bits within "x" at position "p" and with a bit field width, "w". Bits positions are counted from right to left starting with zero. A field is defined from a position and upwards. The result "y" is sign extended. code <w@ ( addr -- 16b) "16b" is the value at "addr". The value is sign extended to the stack (cell) width. code @ ( addr -- 32b) "32b" is the value at "addr". Primary variable value access function. code b! ( x y p -- z) Returns "z", the result of setting the bit at position "p" in "y" according to the value of "x". The bit is set to zero if "x" is zero else one. code b@ ( x p -- y) Returns "true" if the bit a position "p" in "x" is one else "false". code bounds ( addr1 n -- addr2 addr1) Converts vector address and size to boundary address suitable for a "do"-loop. "addr2" is the end address of the vector, i.e., the sum of "addr1" and "n". code c! ( 8b addr -- ) The postfix assignment operator. Store "8b" at "addr". code c@ ( addr -- 8b) "8b" is the value at "addr". The value is not sign extended. code cmove ( addr1 addr2 u -- ) Move the "u" bytes at address "addr1" to "addr2". The byte at "addr1" is moved first, proceeding toward high memory. If "u" is zero nothing is moved. code cmove> ( addr1 addr2 u -- ) Move the "u" bytes at address "addr1" to "addr2". The move begins by moving the byte at ("addr1"+"u"-1) to ("addr2"+"u"-1) and proceeds to successively lower addresses for "u" bytes. If "u" is zero nothing is moved. Useful for sliding a string towards higher addresses. September 17, 1990 4 FORTH(3X) FORTH(3X) code count ( addr1 -- addr2 +n) "addr2" is "addr1"+1 and "+n" is the length of the counted string at "addr1". The byte "addr1" contains the byte count "+n". Range of "+n" is [0..255]. code f! ( x y p w -- z) Inserts the value of "x" into "y" at the bit field which is defined by the position "p" and with the width "w". The value "x" is shifted and masked into "y" to form the result "z". code f@ ( x p w -- y) Field access within a 32-bit quantity. "y" are the bits within "x" at position "p" and with a bit field width, "w". Bits positions are counted from right to left starting with zero. A field is defined from a position and upwards. code fill ( addr u 8b -- ) "u" bytes of memory beginning at "addr" are set to "8b". No action is taken is "u" is zero. code w! ( 16b addr -- ) The postfix assignment operator. Store "16b" at "addr". code w@ ( addr -- 16b) "16b" is the value at "addr". The value is not sign extended. Logic The Forth-83 Standard logic functions. The tile forth kernel extends the basic function set with boolean constants and a boolean conversion function. All logic functions manipulate their parameters bit-by-bit. code and ( 32b1 32b2 -- 32b3) "32b3" is the bit-by-bit logical and of "32b1" and "32b2". code boolean ( n -- bool) Maps numerical value to a boolean value, "true" or "false". Non-zero values are mapped to "true" and zero to "false". constant false ( -- 0) The constant "false" represented by the value zero. code or ( 32b1 32b2 -- 32b3) "32b3" is the bit-by-bit inclusive-or of "32b1" with "32b2". September 17, 1990 5 FORTH(3X) FORTH(3X) code not ( 32b1 -- 32b2) "32b2" is the one's complements of "32b1". constant true ( -- -1) The constant "true" represented by the value minus one. code xor ( 32b1 32b2 -- 32b3) "32b3" is the bit-by-bit exclusive-or of "32b1" with "32b2". Arithmetic The Forth-83 Standard arithmetic word set. The tile forth kernel extends the Forth-83 Standard with arithmetic functions for shifting and additional numeric constants. Double number width arithmetic function such as "d+" and "dnegate" are not implemented as tile forth is a 32-bit implementation. Arithmetic errors are caught by the tile forth kernel and passed to the application as signals. An exception block may be used to catch the signal. code * ( w1 w2 -- w3) "w3" is the least-significant 32 bits of the arithmetic product of "w1" times and "w2". code */ ( w1 w2 w3 -- w4) "w1" is first multiplied by "w2" producing an intermediate 32-bit result. "w4" is the floor of the quotient of the intermediate 32-bit result divided by the divisor "w3". The product of "w1" times "w2" is maintained as an intermediate 32-bit result for greater precision then the otherwise equivalent sequence: "w1 w2 * w3 /". An error condition results if the divisor is zero and an exception is raised. code */mod ( w1 w2 w3 -- w4 w5) "w1" is first multiplied by "w2" producing an intermediate 32-bit result. "w4" is the remainder and "w5" is the floor of the quotient of the intermediate 32-bit result divided by the divisor "w3". A 32-bit intermediate product is used as for "*/". "w4" has the same sign as "w3" or is zero. An error condition results if the divisor is zero and an exception is raised. code + ( w1 w2 -- w3) "w3" is the arithmetic sum of "w1" and "w2". code - ( w1 w2 -- w3) "w3" is the result of subtracting "w2" from "w1". constant -1 ( -- -1) Constant minus one. September 17, 1990 6 FORTH(3X) FORTH(3X) constant -2 ( -- -2) Constant minus two. constant -4 ( -- -4) Constant minus four. code / ( w1 w2 -- w3) "w3" is the floor of the quotient of "w1" divided by the divisor "w2". An error condition results if the divisor is zero. code /mod ( w1 w2 -- w3 w4) "w3" is the remainder and "w4" the floor of the quotient of "w1" divided by the divisor "w2". "w3" has the same sign as "w2" or is zero. An error condition results if the divisor is zero and an exception is raised. constant 0 ( -- 0) Constant zero. constant 1 ( -- 1) Constant one. code 1+ ( w1 -- w2) "w2" is the result of adding one to "w1" according to the operation of "+". code 1- ( w1 -- w2) "w2" is the result of subtracting one to "w1" according to the operation of "-". constant 2 ( -- 2) Constant two. code 2* ( n1 -- n2) "n2" is the result of arithmetically shifting "n1" left one bit. The sign is included in the shift and remains unchanged. code 2+ ( w1 -- w2) "w2" is the result of adding two to "w1" according to the operation of "+". code 2- ( w1 -- w2) "w2" is the result of subtracting two to "w1" according to the operation of "-". code 2/ ( n1 -- n2) "n2" is the result of arithmetically shifting "n1" right one bit. The sign is included in the shift and remains unchanged. September 17, 1990 7 FORTH(3X) FORTH(3X) constant 4 ( -- 4) Constant four. code << ( n1 n2 -- n3) "n3" is the result of logically shifting "n1" left "n2" steps. code >> ( n1 n2 -- n3) "n3" is the result of logically shifting "n1" right "n2" steps. code abs ( n -- u) "u" is the absolute value of "n". code max ( n1 n2 -- n3) "n3" is the greater of "n1" and "n2" according to the operation of ">". code min ( n1 n2 -- n3) "n3" is the lesser of "n1" and "n2" according to the operation of "<". code mod ( n1 n2 -- n3) "n3" is the remainder after dividing "n1" by divisor "n2". "n3" has the same sign as "n2" or is zero. An error condition results if the divisor is zero or if the quotient falls outside of the numerical range. code negate ( n1 -- n2) "n2" is the two's complement of "n1", i.e., the difference of zero less "n1". constant nil ( -- 0) Constant for a nil pointer. code um* ( u1 u2 -- u3) "u3" is the unsigned product of "u1" times "u2". All values and arithmetic are unsigned. code um/mod ( u1 u2 -- u3 u4) "u3" is the remainder and "u4" is the floor of the quotient after dividing "u1" by the divisor "u2". All values and arithmetic are unsigned. An error condition results if the divisor is zero or if the quotient lies outside the numerical range. Comparison The Forth-83 Standard comparison word set. The tile forth kernel extends the standard with an integer range test function. The kernel does not implement double number comparison functions. Boolean values "true" and "false" are represented with "-1" and "0". September 17, 1990 8 FORTH(3X) FORTH(3X) code 0< ( n -- bool) Returns "true" if "n" is less than zero (negative). code 0= ( w -- bool) Returns "true" if "w" is zero. code 0> ( n -- bool) Returns "true" if "n" is greater than zero. code < ( n1 n2 -- bool) Returns "true" if "n1" is less than "n2". code = ( w1 w2 -- bool) Returns "true" if "w1" is equal to "w2" code > ( n1 n2 -- bool) Returns "true" if "n1" is greater than "n2" code ?within ( value lower upper -- bool) Tests if the parameter "value" is within the range "lower" to "upper". Returns "true" if within the range else "false". code u< ( u1 u2 -- bool) Returns "true" if "u1" is less than "u2". Numeric Conversion The Forth-83 Standard numeric conversion functions. The tile forth kernel extends the standard with string to number converter, and general number literal recognition. code # ( +d1 -- +d2 ) The remainder of "+d1" divided by the value of "base" is converted to a ASCII character and appended to the output string toward lower memory addresses. "+d2" if the quotient and is maintained for further processing. Typically used between "<#" and "#>". code #> ( x -- addr +n) Pictured numeric output conversion is ended dropping "x". "addr" is the address of the resulting output string. "+n" is the number of characters in the output string. "addr" and "+n" together are suitable for "type". code #s ( +x -- 0) "+x" is converted appending each resultant character into the pictured numeric output string until the quotient is zero. A single zero is appended to the output string if the number was initially zero. Typically used between "<#" and "#>". September 17, 1990 9 FORTH(3X) FORTH(3X) code <# ( x -- ) Initialize pictured numeric output conversion. The words: "<# # #s hold sign #>" can be used to specify the conversion of a number into an ASCII text string stored in right-to-left order. code ?number ( str -- [n true] or [str false]) recognizer Convert a string of character to a number using the current "base". If the conversion is not possible the string is returned with a "false" flag indicating that the conversion failed otherwise the conversion value, the number, and a "true" flag is returned. variable base ( -- addr) The address of a variable containing the current numeric conversion radix. code binary ( -- ) Set the input-output numeric conversion "base" to 2. code convert ( +d1 addr1 -- +d2 addr2) "+d2" is the result of converting the characters within the text beginning at "addr1"+1 into digits, using the value of "base", and accumulating each into "+d1" after multiplying "+d1" by the value of "base". Conversion continues until an inconvertible character is encountered. "addr2" is the location of the first inconvertible character. code decimal ( -- ) Set the input-output numeric conversion "base" to 10. code hex ( -- ) Set the input-output numeric conversion "base" to 16. code hold ( char -- ) "char" is inserted into a pictured numeric output string. Typically used between "<#" and "#>". code octal ( -- ) Set the input-output numeric conversion "base" to 8. code sign ( n -- ) If "n" is negative, an ASCII "-" (minus sign) is appended to the pictured numerical output string. Typically used between "<#" and "#>". Control Structures The Forth-83 Standard control flow word set. The tile September 17, 1990 10 FORTH(3X) FORTH(3X) forth kernel extends the basic set of control structures with environment arguments access, conditional compilation, case structure, additional loop constructs, and recursion words. code #else ( -- ) immediate Used in the following form: <flag> #if <true-part> #else <else-part> #then Marks the beginning of a "else"-part of a conditional code section. code #if ( flag -- ) immediate Used in the following form: <flag> #if <true-part> [ #else <false-part> ] #then Marks the beginning of a conditional code section. The else section is optional. code #ifdef ( -- ) immediate Used in the following form for testing if a symbol already is available: #ifdef <name> <true-part> [ #else <false-part> ] #then If <name> is available in the current search chain "context" the true section of code is executed or compiled according to mode else the optional false section. code #ifundef ( -- ) immediate Used in the following form: #ifundef <name> <true-part> [ #else <false-part> ] #then Performs the same function as "#ifdef" but the true section is executed if the symbol is not available in the current search chain. code #then ( -- ) immediate Used in the following form: <flag> #if <true-part> [ #else <false-part> ] #then Marks the end of a conditional code section. code +loop ( n -- ) immediate compilation "n" is added to the loop index. If the new index was incremented across the boundary between limit-1 and limit then the loop is terminated and the loop control parameters are discarded. When the loop is not terminated, execution continues to just after the corresponding "do". "+loop" is not available outside a colon definition. code ?do ( w1 w2 -- ) immediate compilation Used in the following forms: ?do ... { i | leave } ... loop or ?do ... { i | leave } ... +loop September 17, 1990 11 FORTH(3X) FORTH(3X) Begins a checked entry loop which terminates based on control parameters. The loop index begins at "w2", and terminates based on the limit "w1". See "loop" and "+loop" for details on how the loop is terminated. If "w1" and "w2" are equal the loop section is skipped. code abort ( -- ) Clears the data stack and performs the function of "quit". No message is displayed. code abort" ( flag -- ) immediate compilation Used in the following form: <flag> abort" <abort-message> " When later executed, if "flag" is true the <abort- message> delimited by close quote, is displayed and then a system dependent error abort sequence, including the function "abort", is performed. If "flag" is false, the flag is dropped and execution continues. The blank following abort" is not part of the <abort-message>. code again ( -- ) immediate compilation Used in the following form to compile an eternal loop: begin ... again The loop construct may only be left by an "abort" or an "exit" word in the code section of the loop. code argc ( -- num) Returns the number of arguments passed from the environment. The first argument is always the name of the application: "forth" or the name of the start symbol. code argv ( n -- str) Given an index returns the corresponding argument string. The "string" vocabulary words may be used for process an argument string. code begin ( -- ) immediate compilation Used in the following forms: begin ... <flag> while ... repeat or begin ... <flag> until grotty:t:temp:11317:fatal error: integer expected or begin ... again "begin" marks the start of a word sequence for repetitive execution. A "begin-while-repeat" loop will repeat until <flag> is false. "begin-until" loop will be repeated until <flag> is true and "begin-again" will repeat until "abort"-ed. The words after "until" and "repeat" will be executed when either loop is finished. September 17, 1990 12 FORTH(3X) FORTH(3X) code bye ( -- ) Leaves the interaction level and exits to the outer support system (if any). code case ( value -- ) immediate compilation Used in the following form: case <case-structure> { <default-part> } endcase to mark the beginning of a case structure which should contain a one or several case statements: <case-value> of <case-part> endof The code section after the last case value part will receive "value" as a parameter thus a default behavior is easy implemented. The default section may only copy this value as "endcase" is an implicit "drop". code do ( w1 w2 -- ) immediate compilation Used in the following forms: do ... { i | leave } ... loop or do ... { i | leave } ... +loop Begins a loop which terminates based on control parameters. The loop index begins at "w2", and terminates based on the limit "w1". See "loop" and "+loop" for details on how the loop is terminated. The loop is always executed at least once. code else ( -- ) immediate compilation Used in the following form: <flag> if <true-part> else <false-part> then in a conditional structure to mark the beginning of the false section. This section is executed when the <flag> is "false". The true section is then skipped. code endcase ( -- ) immediate compilation Used in the following form: case <case-structure> { <default-part> } endcase to mark the end of a case structure. code endof ( -- ) immediate compilation Used in the following form: <case-value> of <case-part> endof to mark the end of a cast value structure. code execute ( addr -- ) The word definition indicated by "addr" is executed. An error condition exists if "addr" is not a compilation address. code exit ( -- ) compilation Compiled within a colon definition such that when executed, the colon definition returns control to the definition that passed control to it by September 17, 1990 13 FORTH(3X) FORTH(3X) returning control to the return point on the top of the return stack. An error condition exists if the top of the return stack does not contain a valid return point. May not be used within a "do-loop" or "do-+loop" or an "exception"-block. code i ( -- w) compilation "w" is a copy of the current loop index. May only be used in the form: do ... { i | leave } ... loop or do ... { i | leave } ... +loop "i" is not visible outside a colon definition, i.e., when text interpreting and should only be used within a loop-block. code if ( flag -- ) immediate compilation Used in the following form: <flag> if <true-part> [ else <else-part> ] then If "flag" is true, the words following "if" are executed and the words following "else" until just after "then" are skipped. The "else" part is optional. If "flag" is false, words from "if" through "else", or from "if" through "then" (when no "else" is used) are skipped. code j ( -- w) compilation "w" is a copy of the index of the next outer loop. May only be used within a nested "do-loop" or "do-+loop" in the form: do ... do ... { i | j | leave } ... loop ... loop "j" is not visible outside a colon definition, i.e., when text interpreting. code leave ( -- ) compilation Transfers execution to just beyond the next "loop" or "+loop". The loop is terminated and the loop control parameters are discarded. May only be used in the following forms: do ... { i | leave } ... loop or do ... { i | leave } ... +loop "leave" may appear within other control structures which are nested within the "do-loop" structure. More than one "leave" may appear within a do-loop. code loop ( -- ) immediate compilation Increments the "do-loop" index by one. If the new index was incremented across the boundary between limit-1 and limit the loop is terminated and the loop control parameters are discarded. When the loop is not terminated, execution continues to just after the corresponding "do". September 17, 1990 14 FORTH(3X) FORTH(3X) code of ( value -- ) immediate compilation Used in the following form: <case-value> of <case-part> endof within a case structure to define a value case. code quit ( -- ) Clears the return stack, sets interpret state, accepts new input from the current input device, and begins text interpretation. No messages is displayed. code recurse ( -- ) immediate compilation Used within a definition to make a recursive call to the current definition. code repeat ( -- ) immediate compilation Used in the following form: begin ... <flag> while ... repeat At execution-time, "repeat" continues execution to just after the corresponding "begin". code tail-recurse ( -- ) immediate compilation Used within a definition to create a recursive call to the current definition without saving return status. This is an efficient way of generating iterative forms as tail recursive calls may be performed any number of times within a definition and corresponds to a branch to the beginning of the definition. code then ( -- ) immediate compilation Used in the following form: <flag> if <true-part> [ else <else-part> ] then Marks the end of a conditional statement "if-else- then". code until ( flag -- ) immediate compilation Used in the following form: begin ... <flag> until Marks the end of a "begin-until" loop which will terminate based on "flag". If "flag" is true, the loop is terminated. If "flag" is false, execution continues to just after the corresponding "begin". code while ( flag -- ) immediate compilation Used in the following form: begin ... <flag> while ... repeat Selects conditional execution based on "flag". When "flag" is true, execution continues to just after the "while" through to the "repeat" which then continues execution to just after the "begin". When "flag" is false, execution continues to just after the "repeat", exiting the control structure. September 17, 1990 15 FORTH(3X) FORTH(3X) Terminal Input/Output The Forth-83 Standard terminal interaction functions. The tile forth kernel extends the basic set of input and output functions with field format output and access of the current input source file name and the current line number count. code . ( n -- ) The absolute value of "n" is displayed in a free field format with a leading minus sign if "n" is negative. A space is emit after the number. code ." ( -- ) immediate compilation Used in the following form within a code definition: <output-string> " Later execution will display the characters <output-string> up to but but including the delimiter (close-quote). The blank following the "." " is not part of the <output-string> but the word separator. code .( ( -- ) immediate Used in the following form: .( <output-comment> ) The characters <output-comment> up to but not including the delimiter (closing-parenthesis) are displayed. The blank following ".(" is not part of the <output-comment>. code .s ( -- ) Displays the current parameter stack contents in the format: [ <depth> ] <bottom> \ ... \ <top> code ascii ( -- char) immediate Used in the following form: ascii <character> ( -- char) to create a character literal. code cr ( -- ) Emits ASCII characters carriage-return and line- feed. code emit ( x -- ) The least-significant 7-bit ASCII character is displayed. code expect ( addr +n -- ) Receive characters and store each into memory.